package YAVMM::Settings;
use warnings;
use strict;

use Moose::Role;
#with 'MooseX::Object::Pluggable';

use TryCatch;
use FindBin;

use YAVMM::Error::UnknownSetting;

requires qw(add commit get reread set unset);

our $VERSION = '0.0.1';

sub commit {};

sub _replace_macros {
    my $str = shift;

    $str =~ s/\%bin\%/$FindBin::Bin/eg;

    return $str;
}

## Moose clean-up
no Moose::Role;
#__PACKAGE__->meta->make_immutable;
1;

__END__

=head1 NAME

YAVMM::Settings - Role providing access to application settings

=head1 VERSION

This documentation refers to version 0.0.1

=head1 SYNOPSIS

=head1 DESCRIPTION

This cannot be used directly. You need to use one of the classes that
implement this role.

=head1 MACROS

Settings may contain macros. This is the list of known macros.

=over

=item %bin%

The path to the binary.

=back

=head1 METHODS

=head2 add(%setting)

Add a new setting to the settings database.

=over

=item section

B<Required:> Section name

=item key

B<Required:> Key name

=item comment

A description of the key

=item example

An example of a valid value

=back

TODO: Throws SettingExists(?)

=head2 commit

Ensure that changes made to the settings are saved. This may be a noop
for some settings databases.

=head2 get(section, key)

Get a setting from the settings backend. It takes two arguments:
the section name and the key.

The returned value must be a scalar but may be a reference to a list
or hash. get() should return 'undef' if the setting is not found.

=head2 reread()

Reread/reload the settings from the database. This may be a noop
for some settings databases.

=head2 set(section, key, value)

Add a setting to the settings backend. It takes three arguments:
the section name, the key and the value. The value must be a scalar
(not a reference).

Use a value of 'undef' to unset a setting.

TODO: Throws UnknownSetting(?)

=head2 unset(section, key)

Unset a key. This is the same as calling set() with a value of 'undef'.

TODO: Throws UnknownSetting(?)

=head1 PRIVATE METHODS

=head2 Str $replaced = _replace_macros (Str $setting)

=head1 BUGS

Bugs may be reported at http://code.google.com/p/yavmm/issues/list.

=head1 AUTHOR

Randy Smith  (perlstalker@vuser.org)

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2010 Randall Smith (perlstalker@vuser.org). All rights reserved.

YAVMM is dual licensed under the Perl Artistic License and GPLv2
or any later version.
